home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 3 / Cream of the Crop 3.iso / comm / jmtl028c.zip / JAMTOOL.DOC < prev    next >
Text File  |  1994-04-07  |  19KB  |  513 lines
  1.  
  2.                           -==* JamTool 0.28 *==-
  3.  
  4.                             By James McOrmond
  5.                               April 7, 1994
  6.  
  7.  
  8. Note: Contact addresses, and the Changelog are at the end of this file.
  9.  
  10. -----------------------------------------------------------------------
  11.  
  12. 1) Installing JamTool
  13.  
  14. There   are   two   versions  of   Jamtool  included  in  this  archive
  15. (bin/Jamtool_T and bin/Jamtool_I).  The T version uses Traplist.library
  16. for  nodelist lookups,  and the I  version  uses  Igen.Library for  its
  17. nodelist lookups.  If you are planning on installing a nodelist on your
  18. system, you should select which of these two formats you wish to use,
  19. and pickup the utilities for that nodelist format.
  20.  
  21. The following files are available from my system:
  22.  
  23. IGEN1a34.lzh - IGEN Nodelist utilities.
  24. Traplist.lha - Traplist Nodelist Utilities. (traplist.library 5.2)
  25.  
  26. It is  recommended  to rename  the version  of JamTool  that  you  have
  27. selected  to use,  to JamTool  and make it  resident in  your  startup-
  28. sequence.  If you do not wish to spare the ram to make JamTool resident,
  29. make sure you put it somewhere in your search path.
  30.  
  31. An alias such as:
  32.  
  33. "alias lookup jamtool -ldcn "
  34.  
  35. is quite usefull.  (Old TrapDoor  users may  want to do a similar alias
  36. for the GetNode command).
  37.  
  38. This alias will add systems to your  cache list (if you remove the c it
  39. won't touch your cache).   You can use this with JTPhone to add systems
  40. to your phonebook from the nodelist.
  41.  
  42. -----------------------------------------------------------------------
  43.  
  44. 2) JTPhone
  45.  
  46. JTPhone is a new program i've added to the package.  It is used to edit
  47. the phone book file that Jamtool uses for its lookups.  The menu system
  48. is  very self-explanitory  so you should have no problems  figuring out
  49. what  you are  doing.   Basically  it allows  you to  edit the  list of
  50. systems in the s:JamTool.Phone list.  Because it creates your phonebook
  51. you do  not have to edit it manuall,  and you don't really need to know
  52. the format of the files either.   JTPhone also has an  option to import
  53. your cache list, so if you've done some outbound dialing to new systems
  54. and JamTool did a lookup for it,  and you now want  to add them to your
  55. phone book, you can easily do this.   It is  recommended that you strip
  56. down the Flags list.   Usually, you'll  just want  to list the relevent
  57. modem flags in there (V32b, Zyx, HST, etc.. whatever you support).
  58.  
  59. -----------------------------------------------------------------------
  60.  
  61. 3) Using JamTool with JamMail
  62.  
  63. JamMail is my own  WPL.library mailer.  If you are  running JamMail  on
  64. your  system  (or  are now  installing  it),  you do not  need  to read
  65. section 4 since JamMail looks after this stuff itself.
  66.  
  67. -----------------------------------------------------------------------
  68.  
  69. 4) Using JamTool in your own Applications (or from the CLI/Shell)
  70.  
  71. Usage: jamtool -command option {option} {option}.....
  72.  
  73.        jamtool -a line
  74.        jamtool -d wazoo.cap line
  75.        jamtool -e StartTime EndTime env:variable
  76.        jamtool -i env:variable
  77.        jamtool -l{c}{n}{d}{v} Address {nodelistpath}
  78.        jamtool -r system response
  79.        jamtool -s {u}
  80.        jamtool -t filename device unit baud flags
  81.        jamtool -v line
  82.  
  83.  
  84. ------
  85. AKA Lookup: (-a)
  86.  
  87.  
  88.   This function is used with the EMSI handshaking.  It takes the line
  89. number as the command line argument, and does a lookup (phone book only)
  90. of each address in the Env:$(line).Remote.Addresses variable.
  91.  
  92.   It creates at least 3 new Env:Variables: $(line).Remote.Addresses.Valid,
  93. $(line).Remote.Addresses.Invalid, and $(line).Remote.Addresses.Unknown.
  94.  
  95.   The Addresses in the Valid and the Unknown variables should be used
  96. for the BeginSession commands, and the Invalid addresses should be
  97. logged for the Sysop to deal with.
  98.  
  99.   The line number is added to the front of each variable so there are
  100. no problems on multi-line systems.
  101.  
  102.   As of version 0.28 of JamTool, it will create multiple variables if the
  103. list of addresses for this variable is longer than 255 characters.
  104.  
  105.   Ie.  If there are 40 addresses in the unknown list, thats approximately
  106. 800 characters (average of 20 characters an address), likely four
  107. variables will be written.  They will be named:
  108.  
  109. $(line).remote.addresses.unknown, $(line).remote.addresses.unknown.2
  110. $(line).remote.addresses.unknown.3, $(line).remote.addresses.unknown.4
  111.  
  112. The exact size of those variables, will depend on the length of the
  113. address that goes over the 200 character mark.
  114.  
  115. ------
  116. Lookup: (-l)
  117.  
  118.  
  119.   This is  the function  you will be  using to find the phone number or
  120. password  of a system  you want to  have a session with.   There is one
  121. required option, which is the address you are looking for, and a second
  122. option which is required if you turn on Env: Variables.
  123.  
  124.   The Lookup  function  is the  only function  where I check  the other
  125. letters of the command  option.   If a c is found,  the t:jamtool.cache
  126. file  will be  used when appropriate.   If an n is found,  the Nodelist
  127. will be searched when appropriate.   If a d is found,  the display will
  128. have a little bit more information than when its not.   If a v is found
  129. then Env: variables will be written if the system is found.
  130.  
  131.  The Flow of the Lookup function is as follows
  132.  
  133.  Look for the system in the Phonebook.
  134.  If not found and the Cache is enabled, look there.
  135.  If not found and the Nodelist is enabled look there
  136.  If I found it in the nodelist, and the cache is on, add to the cache
  137.  If I found the system, and the variables are on, write the variables.
  138.  
  139.  
  140.  3. Work:jamtool> jamtool -lcnd 163/0
  141. Address: FIDONET#1:163/0.0 ()
  142. System : Canada's Capital
  143. Phone  : 1-613-744-5750  Type: FIDO
  144. Sysop  : Susan_Duncan (Ottawa_ON)
  145. Flags  : XA,CM,MO,V42b,V32b,9600
  146. Hub    : 0, Region: 12
  147. Cost   : 0
  148.  
  149. This is the output  displayed when Full  display is turned on,  and the
  150. system was found in the nodelist (not the Cache or phonebook).
  151.  
  152.  3. Work:jamtool> jamtool -lcdn 163/109
  153.  Address: FIDONET#1:163/109.0 (-)
  154.  Phone  : 1-613-230-2282  Type: FIDO
  155.  Sysop  : Russell_McOrmond (Ottawa_ON)
  156.  Flags  : ZYX
  157.  
  158. This  is the output  displayed  when Full display is  turned on and the
  159. system  is found  in the  Cache  or Phonebook.   The Phone  number line
  160. would not be displayed if the extended display option was not on.
  161.  
  162. The following ENV: variables are set when you turn Env: Variables on.
  163.  
  164. $(stem).City
  165. $(stem).Cost
  166. $(stem).Flags
  167. $(stem).MaxBaud
  168. $(stem).Number
  169. $(stem).Password
  170. $(stem).SiteName
  171. $(stem).Sysop
  172.  
  173. ------
  174.  Type file: (-t)
  175.  
  176. This function is  relatively straight  forward.  It takes the  required
  177. command  line  options,  and outputs  a regular  text file  to the user
  178. through the given serial device.
  179.  
  180. I run it in Jammail.wpl like this.
  181.  
  182.   system "jamtool -t text:$(username) $(device) $(unit) $(baud) $(serflags)"
  183.  
  184. which prints a text file name (in the variable username) to the user on
  185. this line.
  186.  
  187.  
  188. ------
  189.  Dialing Response Code: (-r)
  190.  
  191. This function takes two options, the first one being the systems address
  192. and the second being the response type as returned from the modem after
  193. a dial ("CONNECT", "BUSY", "MAID", etc).
  194.  
  195. The first parameter, is not to be a regular Fido style address.  If the
  196. system called, was not a Fidonet system, the address is passed unmodified
  197. to JamTool, if the address is a Fidonet system, then the address should
  198. be sent in the following form:
  199.  
  200. Zone.Net.Node.Point.Domain.
  201.  
  202. The following WPL code is used in JamMail for this function.
  203.  
  204.  
  205.    cmpi $(remote.type) FIDO
  206.    FalseJump NotFidoDoDial
  207.    RexxMsg SY REXX "Address 'COMMAND' 'JamTool -r $(Remote.Zone).$(Remote.Net).$(Remote.Node).$(Remote.Point).$(Remote.Domain) $(event)'"
  208.    Jump AfterTypeCheckDoDial
  209.   NotFidoDoDial:
  210.    RexxMsg SY REXX "Address 'COMMAND' 'JamTool -r $(Remote.Address) $(event)'"
  211.   AfterTypeCheckDoDial:
  212.  
  213. This code is immediately after the GetResponse command after the Dial
  214. command.
  215.  
  216. ------
  217.  Scheduler: (-s) option
  218.  
  219.  This function scans XferQ.library for systems with outbound mail of at
  220. least priority 50  (crash) (or the number  stored in the ENV:  variable
  221. "minpri"),  and scans the UUSPOOL:  directory for  C.#? files  to go to
  222. sites listed in your UULIB:l.sys file and creates a list of environment
  223. variables with the sites to call.
  224.  
  225.  $(JamTool/todial)   the number of sites to dial
  226.  $(JamTool/todial-1) site number 1 to dial
  227.  $(JamTool/todial-2) site number 2 to dial
  228.  
  229.  etc..
  230.  
  231. The Scheduler  built into  versions of  JamMail higher than .96 all use
  232. this function.
  233.  
  234. As of JamTool 0.23 this scheduler now counts the number of busy signals
  235. and failed connections (via the -r option above), and will dial less
  236. often if you still have not connected to this system.  The following
  237. function is used to determine the number of "loops" through the
  238. scheduler will be waited until the next dial for this system.
  239.  
  240. towait = (((bad*3)+busy) / 10)
  241.  
  242. Each bad connect is equivalent to 3 busy signals.  After each 15 busy
  243. signals, the system will up the number of loops that it must wait
  244. before dialing the system again.
  245.  
  246.  
  247. ------
  248.  Wazoo Bit Decode: (-d)
  249.  
  250. This option  provides  you with  a "pretty"  bit display for your logs.
  251. Instead  of displaying just the Wazoo Bits number, you can also display
  252. exactly what each bit means.
  253.  
  254. In JamMail.wpl, this is how I use the decode option.
  255.  
  256.   System "JamTool -d $(remote.wzcap) $(line)"
  257.  
  258. If  $(remote.wzcap)  contained the  number 49165, the env:$(line).WaZoo
  259. variable would include the following string.
  260.  
  261.  >  DietIFNA ZedZip ZedZap +Freq +Domain
  262.  
  263. which you can print in the Wazoo: display routine in your .wpl language
  264. file.
  265.  
  266.  
  267. ------
  268.  IsValid: (-i)
  269.  
  270. This option takes the name of an environment variable as its option.
  271. It will scan the line for special control characters and tell you if
  272. the string is invalid.  It will return 5 if it finds a character that
  273. it doesn't like.
  274.  
  275. The following characters are scanned for:
  276.  
  277. '  `  ~  $  "
  278.  
  279.  
  280. ------
  281.  Total Session time Calculator: (-e)
  282.  
  283. This option takes 3 options.   The Start time (hh:mm:ss), the  End time
  284. (hh:mm:ss)  and the variable name that it will stick  the difference in
  285. (hh:mm:ss  format).   This is used  to provide  the Total  Session Time
  286. displayed on the End of Session log line.
  287.  
  288.  
  289. > [1] 19:29:14 End of Session with FidoNet#1:224/30.0 Duration: 00:01:25
  290.  
  291.  
  292. ------
  293.  Pretty Version Strings: (-v)
  294.  
  295. This option  will possibly be removed  from the  program as  its not as
  296. relevent as it first was when I first wrote it.
  297.  
  298. I run it in the following way in  my Startup: routine in my JamMail.Wpl
  299. file.
  300.  
  301.  startup:
  302.    set currentlog all
  303.    set stack 32000
  304.    PutLog ""
  305.    system "jamtool -v M"
  306.    PutLog "[M] $<time> Startup on ${M.Date} with ${WPLName}"
  307.    PutLog "[M] $<time> ${M.Version}"
  308.  
  309. which produces a log such as:
  310.  
  311.  >
  312.  > [M] 14:05:46 Startup on Sunday 21-Feb-93 with WPL 0.86.01
  313.  > [M] 14:05:46 Kickstart version 37.175. Workbench version 37.71
  314.  
  315. The $(stem).Version string  is really not necessary,  since Version can
  316. be run as an  Echo option in KS2.0 (to get rid of  the line feed on the
  317. end),  but I had  done this option  before we found this out.  The only
  318. difference between  $(stem).Date and the  internal $<date>  function is
  319. the day word, which is what i was wanting.
  320.  
  321. -----------------------------------------------------------------------
  322.  
  323. 5) The S:Jamtool.phone and t:Jamtool.Cache files
  324.  
  325. Both of  these files  are  exactly the  same format.   Actually, when I
  326. first wrote the version of  JamTool that  supported these files, I used
  327. jamtool to create a  t:jamtool.cache  file (through nodelist  lookups),
  328. and then copied this file as my s:jamtool.phone file.
  329.  
  330. The format of the file is as follows.  One system per line.
  331.  
  332. Address Phone Type PassWd Flags Location Sysop
  333.  
  334. The address must be either a text address, or a full 5d FTN address.
  335.  
  336.    eg. Fidonet#1:163/139.0
  337.    
  338. The phone number field is self-explainatory.   This is the number  that
  339. is dialed to reach this system.   (JamMail  users that  are using a  LD
  340. phone  routing service  should look  into the  LDPhone Options  if they
  341. wish to prepend a number to this  phone number).   Local phone  numbers
  342. should not have prefixes and such on them.
  343.  
  344.    eg. 1-613-521-0455
  345.     or:
  346.        521-0455  (if its a local call)
  347.  
  348. There are a few types supported with JamMail.  Users of other  software
  349. may want to put a - in this field if your mailer doesn't use this field
  350. itself.
  351.  
  352.      FIDO - When connected, start a Fidonet session with this site.
  353.      UUCP - When connected, launch UUCICO for a UUCP session.
  354.      NRC  - Used for calling Atomic clock systems.
  355.      TERM - When connected, launch a terminal program.
  356.      FAX  - When connected, lauch fax software (not used yet).
  357.  
  358. Currently JTPhone only supports the first 4.
  359.  
  360. The PassWd field should contain  the password  that you wish to use for
  361. sessions with this system.
  362.  
  363. The Flags  field should contain a bit of information about the modem on
  364. the  other end.  JamMail  uses this field  to check  against  a list of
  365. parameters that the user can configure,  and it will use a  custom dial
  366. string for specific modem types.  If you are importing systems from the
  367. nodelist,  you will  want to clean a  lot of the nodelist flags  out of
  368. this field as you won't be using them.  See section on JTPhone for more
  369. information.
  370.  
  371. The last two fields,  Location and Sysop  are used for display purposes
  372. only.
  373.  
  374. Eg.
  375.  
  376. Fidonet#1:163/109.0 230-2282 FIDO - v32b Ottawa Russell_McOrmond
  377.  
  378. Note:  If you support UUCP sessions  on your system, you  will  need an
  379. entry  for  inbound calls,  and  one for  outbound calls.   The inbound
  380. entry should have a "UU" on the front of the name.
  381.  
  382. eg.
  383.  
  384. Jammys 521-0455 UUCP - v32b,zyx Ottawa James_McOrmond
  385. UUJammys - UUCP passwd v32b,zyx Ottawa James_McOrmond
  386.  
  387. The password field is not currently used on Outbound calls,  so you are
  388. expected to keep working entries in your uulib:l.sys file.
  389.  
  390. The following fields can be replaced by a "-" character if they are not
  391. appropriate, or necessary for that entry.  (JamMail users)
  392.  
  393. Password  - outbound UUCP sessions use l.sys send-expect strings
  394. Phone     - inbound UUCP sessions
  395.  
  396.  
  397. -----------------------------------------------------------------------
  398.  
  399. If you need to contact me, these are my Addresses.
  400.  
  401. FidoNet#1:163/139.0
  402. ZyXELNET#18:163/139.0
  403. InterNet: ab207@Freenet.Carleton.Ca
  404.  
  405. Also you can get ahold of me in any number of the Amiga Fidonet related
  406. conferences (Especially the WELMAT or AMY_Point) conference, as well as
  407. most of the UseNet Comp.Sys.Amiga newsgroups, especially 
  408. Comp.Sys.Amiga.Datacomm.  Since newsgroups do not have a to: name, they
  409. aren't the best way to get ahold of me.  The fastest for internet uses
  410. is the ab207 account.
  411.  
  412. Current versions of JamTool are always available by dialing my system
  413. 1:163/139 (613)521-0455, typing "freq", and then typing "JamTool".
  414. JamTool is included in the JamMail archive, so if you are using JamMail
  415. you do not need to grab this archive seperately.
  416.  
  417. -----------------------------------------------------------------------
  418.  
  419.                ----------=== Jamtool Changelog ===----------
  420.  
  421.  
  422. V0.10 - Intial release.  Sunday February 21, 1993
  423.  
  424. V0.11 - shows all command line arguments in window for debugging.
  425.  
  426. V0.12 - If there is a second digit after the f in the -f option
  427.         (ie -FIDO as in the above example), the tiny display will be
  428.         put there, but if there is only a -f, then there won't be a
  429.         display.  This is to remove the display from being show when
  430.         the Wazoo: routine is looking up the sites password (and City
  431.         in Jammail.wpl).
  432.  
  433. V0.13 - Added regular fido lookup function which displays the same
  434.         information the regular -fido option does, but it doesn't
  435.         set any ENV: variables.      (Thu Feb 25)
  436.  
  437. V0.14 - working on type function.  (Mon Mar 1)
  438.  
  439. V0.14+ - Type function works.  Requires filename, device, unit, baud
  440.         and serial flags ($(serflags) variable).
  441.  
  442. V0.15 - -L option fixed.
  443.  
  444. V0.16 - -S(cheduler) Option added.  Scans for UUCP and Fido outgoing mail
  445.  
  446. v0.17 - fixes to scheduler - does not dial UUCP sites without "any" in the
  447.         second field of the l.sys file.
  448.  
  449. v0.17b - bug fixes
  450.  
  451. v0.17c - something
  452.  
  453. v0.18 - Visual changes as requested by Robert.  Domain displayed in Lookup
  454.         is the same domain given (if one is given).  (bits) part removed
  455.         from WaZoo decode line and +domain moved to last field displayed.
  456.  
  457. v0.18b - -E option.  It subtracts the time difference between the two time
  458.         values given.  This allows me to give the "total session time"
  459.         used in the End of Session log line.
  460.  
  461. v0.20 - completely re-did all of the "lookup options" to use the phone
  462.         book and cache files.  All addresses are parsed by Xferq.Library
  463.         and are converted to uppercase for a case-insensative match on
  464.         the phonebook and cache files.
  465.  
  466. v0.20b - added env:minpri variable for scheduler to set the lowest
  467.         priority that will be scanned for.
  468.  
  469. v0.21 - New Lookup function.  There is now a single Lookup command with
  470.         4 possible flags.
  471.  
  472. v0.21a - Completely cleaned JamTool up.
  473.  
  474. v0.22 - JamTool Phone book editor added to archive.
  475.  
  476. v0.22a - JTPhonebook updated (v1.02).
  477.  
  478. v0.22b - JTPhonebook updated (v1.03).  Optimizing all 3 binaries now.
  479.         JamTool now identifies Hydra in Wazoo Bit field.
  480.         Entry of "Session type" fixed in JTPhone Add function.
  481.  
  482. v0.23 - Scheduler now figures out how often it should dial a system
  483.         based on the number of Busy signals and bad connections it has
  484.         received attempting to dial the system since its last outbound
  485.         connection.  New Option "-r" added used for setting up this
  486.         "Data base" of responses for each system.
  487.         
  488. 0.23b - Scheduler dialing adjuster now changes after 10 "busy" responses
  489.         instead of 15.
  490.  
  491. 0.23c - now changes after 6 busy signals.  A "no carrier" is worth 3
  492.         busy signals itself.
  493.  
  494. 0.24 - 0.26 - lots of small changes - AKA lookup function added
  495.        (missing documentation :-)
  496.  
  497. 0.27 - AKA password lookups are now sped up a very large amount!
  498.        previously the s:jamtool.phone file was searched for each AKA
  499.        and the passwords checked one at a time.  I am now reading
  500.        the s:jamtool.phone into a linked list in ram, and search
  501.        for each AKA that way.
  502.  
  503. 0.28 - AKA password lookups are increased over 0.27 by probably about 10
  504.        times!!!  JamTool now splits up the EMSI AKA variables are less
  505.        than 256 characters (the max for a WPL variable).
  506.  
  507. 0.28b - All functions relating to addresses (lookups, scheduler lists,
  508.         etc..) have all been spead up.  JamTool uses much less CPU now!
  509.         fixed stupid bug with reading the uulib:l.sys file.
  510.  
  511. 0.28c - JTPhone cleaned up a bit.  The phone book is also sorted when
  512.         loaded.
  513.